classdef PathUtils
    % PATHUTILS 路径处理工具类
    % 基于DO-178规则第4条（架构分离原则）
    % 提供路径处理的通用静态方法
    %
    % 功能：
    %   - 判断路径是否为绝对路径
    %   - 标准化路径（消除 .. 和 . 部分）
    %   - 跨平台路径处理（Windows/Unix/Mac）
    %
    % 使用示例：
    %   % 判断是否为绝对路径
    %   isAbs = PathUtils.isAbsolutePath('C:\workspace\project');  % Windows: true
    %   isAbs = PathUtils.isAbsolutePath('/home/user/project');    % Unix: true
    %   isAbs = PathUtils.isAbsolutePath('relative/path');         % false
    %
    %   % 标准化路径
    %   normalized = PathUtils.normalizePath('C:\workspace\..\project');
    %   % 结果: 'C:\project'
    %
    % 设计原则：
    %   - 所有方法都是静态方法，无需实例化
    %   - 跨平台兼容（Windows, Unix, Mac）
    %   - 遵循DO-178规则第2条：明确报告错误，不使用silent fallback
    %
    % 另见: ProjectPathManager, ProjectNamingManager
    %
    % 作者: MBD Platform Team
    % 日期: 2025-10-14
    % 遵循DO-178标准
    
    methods (Static)
        
        function tf = isAbsolutePath(pathStr)
            % ISABSOLUTEPATH 判断路径是否为绝对路径
            % 
            % 输入参数:
            %   pathStr - 路径字符串
            % 输出参数:
            %   tf - 逻辑值，true表示绝对路径，false表示相对路径
            %
            % 示例：
            %   PathUtils.isAbsolutePath('C:\workspace')       % Windows: true
            %   PathUtils.isAbsolutePath('/home/user')         % Unix: true
            %   PathUtils.isAbsolutePath('relative/path')      % false
            %   PathUtils.isAbsolutePath('\\server\share')     % UNC: true
            
            if isempty(pathStr)
                tf = false;
                return;
            end
            
            % Windows系统判断
            if ispc
                % 检查是否以驱动器字母开头 (如 "C:\")
                if length(pathStr) >= 3 && pathStr(2) == ':' && ...
                   (pathStr(3) == '\' || pathStr(3) == '/')
                    tf = true;
                    return;
                end
                
                % 检查是否为UNC路径 (如 "\\server\share")
                if length(pathStr) >= 2 && pathStr(1) == '\' && pathStr(2) == '\'
                    tf = true;
                    return;
                end
                
                tf = false;
                
            % Unix/Linux/Mac系统判断
            else
                % 检查是否以 "/" 开头
                tf = pathStr(1) == '/';
            end
        end
        
        function normalizedPath = normalizePath(pathStr)
            % NORMALIZEPATH 标准化路径，消除多余的 .. 和 . 部分
            % 
            % 输入参数:
            %   pathStr - 路径字符串
            % 输出参数:
            %   normalizedPath - 标准化后的路径
            %
            % 示例：
            %   PathUtils.normalizePath('C:\a\b\..\c')        % 'C:\a\c'
            %   PathUtils.normalizePath('/home/user/../tmp')  % '/home/tmp'
            %   PathUtils.normalizePath('.\relative\path')    % 'relative\path'
            %
            % 实现说明：
            %   - 如果路径存在，使用MATLAB内置函数获取完整路径
            %   - 如果路径不存在，使用手动标准化算法
            %   - 基于规则第2条：不使用silent fallback，明确处理错误
            
            if isempty(pathStr)
                normalizedPath = '';
                return;
            end
            
            % 使用MATLAB内置函数获取完整路径
            % 这会自动处理相对路径中的 .. 和 .
            try
                % 如果路径存在，直接获取完整路径
                if exist(pathStr, 'file') || exist(pathStr, 'dir')
                    whatResult = what(pathStr);
                    if ~isempty(whatResult) && ~isempty(whatResult.path)
                        normalizedPath = whatResult.path;
                    else
                        normalizedPath = pathStr;
                    end
                else
                    % 如果路径不存在，尝试规范化路径字符串
                    normalizedPath = PathUtils.manualNormalizePath(pathStr);
                end
            catch
                % 如果出错，使用手动规范化
                normalizedPath = PathUtils.manualNormalizePath(pathStr);
            end
        end
        
        function normalizedPath = manualNormalizePath(pathStr)
            % MANUALNORMALIZEPATH 手动标准化路径
            % 
            % 输入参数:
            %   pathStr - 路径字符串
            % 输出参数:
            %   normalizedPath - 标准化后的路径
            %
            % 算法说明：
            %   1. 分割路径为部分
            %   2. 处理每个部分：
            %      - 忽略 '.' 和空字符串
            %      - 遇到 '..' 则返回上一级（删除上一个部分）
            %      - 其他部分正常添加
            %   3. 重新组装路径
            %
            % 注意：
            %   - 此方法不检查路径是否存在
            %   - 仅进行字符串级别的规范化
            %   - 跨平台兼容
            
            if isempty(pathStr)
                normalizedPath = '';
                return;
            end
            
            % 分割路径为部分
            if ispc
                pathParts = strsplit(pathStr, {'\', '/'});
            else
                pathParts = strsplit(pathStr, '/');
            end
            
            % 处理路径部分，消除 . 和 ..
            normalizedParts = {};
            for i = 1:length(pathParts)
                part = pathParts{i};
                
                if strcmp(part, '.') || isempty(part)
                    % 忽略当前目录标记和空字符串
                    continue;
                elseif strcmp(part, '..')
                    % 上级目录标记
                    if ~isempty(normalizedParts)
                        normalizedParts(end) = [];
                    end
                else
                    % 正常的目录或文件名
                    normalizedParts{end+1} = part; %#ok<AGROW>
                end
            end
            
            % 重新组装路径
            if ispc
                normalizedPath = strjoin(normalizedParts, '\');
            else
                normalizedPath = strjoin(normalizedParts, '/');
                % 对于Unix系统，如果原路径以/开头，需要保留
                if ~isempty(pathStr) && pathStr(1) == '/'
                    normalizedPath = ['/' normalizedPath];
                end
            end
        end
        
    end
end

